TypeScript-konfiguraatio: Kattava opas tsconfig.json-tiedostoon

TypeScript, JavaScriptin supersetti, tuo staattisen tyypityksen web-kehityksen dynaamiseen maailmaan. Hyvin määritetty tsconfig.json-tiedosto on elintärkeä TypeScriptin koko potentiaalin hyödyntämisessä. Tämä opas tarjoaa kattavan yleiskatsauksen tsconfig.json-tiedostosta, käsitellen olennaiset kääntäjäasetukset, projektin alustuksen ja edistyneet konfiguraatiot.

Mikä on tsconfig.json?

tsconfig.json-tiedosto on konfiguraatiotiedosto, joka määrittelee TypeScript-projektin kääntäjäasetukset. Se kertoo TypeScript-kääntäjälle, miten TypeScript-koodi käännetään JavaScriptiksi. Tämä tiedosto on olennainen projektin rakenteen määrittelyssä, käännössääntöjen asettamisessa ja yhdenmukaisuuden varmistamisessa kehitystiimin kesken, sijaitsipa tiimi sitten yhdessä toimistossa tai hajautettuna useille mantereille.

tsconfig.json-tiedoston luominen

Luodaksesi tsconfig.json-tiedoston, siirry projektisi juurihakemistoon terminaalissa ja suorita seuraava komento:

            tsc --init
            

              
                Copy
              
            
          

Tämä komento luo perusmuotoisen tsconfig.json-tiedoston yleisesti käytetyillä kääntäjäasetuksilla. Voit sitten muokata tiedostoa vastaamaan projektisi erityisvaatimuksia. Tyypillinen tsconfig.json sisältää asetuksia kuten compilerOptions, include ja exclude.

Olennaiset kääntäjäasetukset

compilerOptions-osio on tsconfig.json-tiedoston sydän. Se sisältää laajan valikoiman asetuksia, jotka ohjaavat TypeScript-kääntäjän toimintaa. Tässä on joitakin tärkeimpiä kääntäjäasetuksia:

target

target-asetus määrittää tuotetun JavaScript-koodin ECMAScript-kohdeversion. Yleisiä arvoja ovat ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Oikean kohdeversion valitseminen on ratkaisevan tärkeää yhteensopivuuden varmistamiseksi aiotun suoritusympäristön, kuten selainten tai Node.js-versioiden, kanssa.

Esimerkki:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

module-asetus määrittää moduulikoodin generointityylin. Yleisiä arvoja ovat CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ja ESNext. Moduulijärjestelmän valinta riippuu kohdeympäristöstä ja käytetystä moduulien niputtajasta (esim. Webpack, Rollup, Parcel). Node.js:lle käytetään usein CommonJS:ää, kun taas moderneissa verkkosovelluksissa suositaan ES6:tta tai ESNext:iä moduulien niputtajan kanssa. ESNext:n käyttö antaa kehittäjille mahdollisuuden hyödyntää uusimpia ominaisuuksia ja optimointeja, samalla kun niputtaja hoitaa lopullisen moduulimuodon.

Esimerkki:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

lib-asetus määrittää luettelon kirjastotiedostoista, jotka sisällytetään käännökseen. Nämä kirjastotiedostot tarjoavat tyyppimääritelmät sisäänrakennetuille JavaScript- ja selain-API:eille. Yleisiä arvoja ovat ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String ja monet muut. Sopivien kirjastojen valitseminen varmistaa, että TypeScript-kääntäjällä on tarvittavat tyyppitiedot kohdeympäristöä varten. DOM-kirjaston käyttö mahdollistaa projektin kääntävän koodia, joka käyttää selainkohtaisia API:eja ilman tyyppivirheitä.

Esimerkki:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

allowJs-asetus sallii TypeScript-kääntäjän kääntää JavaScript-tiedostoja yhdessä TypeScript-tiedostojen kanssa. Tämä on hyödyllistä olemassa olevien JavaScript-projektien siirtämisessä TypeScriptiin vaiheittain. Asettamalla tämä arvoon true kääntäjä voi käsitellä .js-tiedostoja, mikä mahdollistaa TypeScriptin asteittaisen käyttöönoton projektissa.

Esimerkki:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

jsx-asetus määrittää, miten JSX-syntaksia käsitellään. Yleisiä arvoja ovat preserve, react, react-native ja react-jsx. preserve säilyttää JSX-syntaksin tulosteessa, kun taas react muuntaa JSX:n React.createElement-kutsuiksi. react-jsx käyttää React 17:ssä esiteltyä uutta JSX-muunnosta, joka ei vaadi Reactin tuomista. Oikean JSX-vaihtoehdon valitseminen on ratkaisevan tärkeää projekteille, jotka käyttävät Reactia tai muita JSX-pohjaisia kirjastoja.

Esimerkki:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

declaration-asetus luo vastaavat .d.ts-määrittelytiedostot jokaiselle TypeScript-tiedostolle. Määrittelytiedostot sisältävät tyyppitietoja ja niitä käyttävät muut TypeScript-projektit käännetyn koodin kuluttamiseen. Määrittelytiedostojen luominen on välttämätöntä uudelleenkäytettävien kirjastojen ja moduulien luomiseksi. Nämä tiedostot antavat muille TypeScript-projekteille mahdollisuuden ymmärtää kirjaston paljastamat tyypit ja rajapinnat ilman, että alkuperäistä lähdekoodia tarvitsee kääntää.

Esimerkki:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

sourceMap-asetus luo lähdekarttatiedostoja, jotka yhdistävät generoidun JavaScript-koodin takaisin alkuperäiseen TypeScript-koodiin. Lähdekartat ovat välttämättömiä TypeScript-koodin virheenjäljityksessä selaimissa ja muissa ympäristöissä. Kun JavaScript-koodissa tapahtuu virhe, lähdekartta antaa kehittäjälle mahdollisuuden nähdä vastaavan TypeScript-koodin virheenjäljittimessä, mikä helpottaa ongelman tunnistamista ja korjaamista.

Esimerkki:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

outDir-asetus määrittää generoitujen JavaScript-tiedostojen tuloshakemiston. Tämä asetus auttaa järjestämään projektin käännöstulokset erottamalla lähdekoodin käännetystä koodista. outDir:n käyttö helpottaa käännösprosessin hallintaa ja sovelluksen käyttöönottoa.

Esimerkki:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

rootDir-asetus määrittää TypeScript-projektin juurihakemiston. Kääntäjä käyttää tätä hakemistoa pohjana moduulien nimien selvittämisessä. Tämä asetus on erityisen tärkeä projekteissa, joilla on monimutkainen hakemistorakenne. rootDir:n oikea asettaminen varmistaa, että kääntäjä löytää kaikki tarvittavat moduulit ja riippuvuudet.

Esimerkki:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

strict-asetus ottaa käyttöön kaikki tiukat tyyppitarkistusasetukset. Tämä on erittäin suositeltavaa uusille TypeScript-projekteille, koska se auttaa havaitsemaan mahdolliset virheet varhaisessa kehitysvaiheessa. Tiukan tilan käyttöönotto pakottaa tiukemmat tyyppitarkistussäännöt, mikä johtaa vankempaan ja ylläpidettävämpään koodiin. On parasta käytäntöä ottaa tiukka tila käyttöön kaikissa uusissa TypeScript-projekteissa.

Esimerkki:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

esModuleInterop-asetus mahdollistaa yhteentoimivuuden CommonJS- ja ES-moduulien välillä. Tämä on tärkeää projekteille, jotka käyttävät molempia moduulityyppejä. Kun esModuleInterop on käytössä, TypeScript hoitaa automaattisesti CommonJS- ja ES-moduulien väliset erot, mikä helpottaa moduulien tuontia ja vientiä näiden kahden järjestelmän välillä. Tämä asetus on erityisen hyödyllinen työskenneltäessä kolmannen osapuolen kirjastojen kanssa, jotka saattavat käyttää eri moduulijärjestelmiä.

Esimerkki:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

moduleResolution-asetus määrittää, miten TypeScript selvittää moduulien tuonnit. Yleisiä arvoja ovat Node ja Classic. Node-moduulien selvitysstrategia on oletusarvo ja perustuu Node.js:n moduulien selvitysalgoritmiin. Classic-moduulien selvitysstrategia on vanhempi ja vähemmän käytetty. Node-moduulien selvitysstrategian käyttö varmistaa, että TypeScript pystyy selvittämään moduulien tuonnit oikein Node.js-ympäristössä.

Esimerkki:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl ja paths

baseUrl- ja paths-asetuksia käytetään moduulien selvityksen määrittämiseen ei-suhteellisille moduulien tuonneille. baseUrl-asetus määrittää perushakemiston ei-suhteellisten moduulien nimien selvittämiseen. paths-asetus antaa sinun yhdistää moduulien nimiä tiettyihin sijainteihin tiedostojärjestelmässä. Nämä asetukset ovat erityisen hyödyllisiä projekteissa, joilla on monimutkainen hakemistorakenne, ja moduulien tuontien yksinkertaistamiseksi. baseUrl:n ja paths:n käyttö voi tehdä koodista luettavampaa ja ylläpidettävämpää.

Esimerkki:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Include- ja Exclude-asetukset

include- ja exclude-asetukset määrittävät, mitkä tiedostot sisällytetään käännökseen ja mitkä tiedostot jätetään pois. Nämä asetukset käyttävät glob-kuvioita tiedostojen nimien vastaavuuteen. include:n ja exclude:n käyttö antaa sinun hallita, mitkä tiedostot TypeScript-kääntäjä käsittelee, mikä parantaa käännöksen suorituskykyä ja vähentää virheitä. On parasta käytäntöä määrittää nimenomaisesti käännökseen sisällytettävät tiedostot.

Esimerkki:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Extends-asetus

extends-asetus antaa sinun periä kääntäjäasetuksia toisesta tsconfig.json-tiedostosta. Tämä on hyödyllistä jaettaessa yhteisiä konfiguraatioasetuksia useiden projektien välillä tai luotaessa peruskonfiguraatioita. extends-asetuksen käyttö edistää koodin uudelleenkäyttöä ja vähentää päällekkäisyyttä. On parasta käytäntöä luoda peruskonfiguraatioita ja laajentaa niitä yksittäisissä projekteissa.

Esimerkki:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Edistyneet konfiguraatiot

Olennaisten kääntäjäasetusten lisäksi tsconfig.json tukee edistyneitä konfiguraatioita erikoistuneisiin skenaarioihin.

Inkrementaalinen kääntäminen

Suurissa projekteissa inkrementaalinen kääntäminen voi merkittävästi parantaa käännösaikoja. TypeScript voi tallentaa välimuistiin aiempien käännösten tulokset ja kääntää uudelleen vain muuttuneet tiedostot. Inkrementaalisen kääntämisen käyttöönotto voi dramaattisesti lyhentää suurten projektien käännösaikoja. Tämä on erityisen tärkeää projekteissa, joissa on suuri määrä tiedostoja ja riippuvuuksia.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Projektiviittaukset

Projektiviittaukset antavat sinun jäsentää suuria TypeScript-projekteja pienempiin, itsenäisiin moduuleihin. Tämä voi parantaa käännösaikoja ja koodin organisointia. Projektiviittausten käyttö voi tehdä suurista projekteista hallittavampia ja helpommin ylläpidettäviä. On parasta käytäntöä käyttää projektiviittauksia suurissa, monimutkaisissa projekteissa.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Mukautetut tyyppimääritelmät

Joskus saatat joutua tarjoamaan tyyppimääritelmiä JavaScript-kirjastoille, joilla ei niitä ole. Voit luoda mukautettuja .d.ts-tiedostoja määrittääksesi tyypit näille kirjastoille. Mukautettujen tyyppimääritelmien luominen antaa sinun käyttää JavaScript-kirjastoja TypeScript-koodissasi uhraamatta tyyppiturvallisuutta. Tämä on erityisen hyödyllistä työskenneltäessä vanhan JavaScript-koodin tai kirjastojen kanssa, jotka eivät tarjoa omia tyyppimääritelmiään.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Parhaat käytännöt

• Käytä Strict Modea: Ota strict-asetus käyttöön tehostaaksesi tyyppitarkistusta.
• Määritä kohdeversio: Valitse sopiva target-versio suoritusympäristöllesi.
• Järjestä tulosteet: Käytä outDir-asetusta erottaaksesi lähdekoodin käännetystä koodista.
• Hallitse riippuvuuksia: Käytä include- ja exclude-asetuksia hallitaksesi, mitkä tiedostot käännetään.
• Hyödynnä Extends-asetusta: Jaa yhteisiä konfiguraatioasetuksia extends-asetuksen avulla.
• Tallenna konfiguraatio versionhallintaan: Tallenna `tsconfig.json` gitiin ylläpitääksesi johdonmukaisuutta kehittäjäympäristöjen ja CI/CD-putkien välillä.

Yleisten ongelmien vianmääritys

tsconfig.json:n konfigurointi voi joskus olla haastavaa. Tässä on joitakin yleisiä ongelmia ja niiden ratkaisuja:

Moduulien selvitysongelmat

Jos kohtaat moduulien selvitysvirheitä, varmista, että moduleResolution-asetus on määritetty oikein ja että baseUrl- ja paths-asetukset on asetettu oikein. Tarkista paths-asetuksessa määritetyt polut varmistaaksesi, että ne ovat oikein. Varmista, että kaikki tarvittavat moduulit on asennettu node_modules-hakemistoon.

Tyyppivirheet

Tyyppivirheitä voi esiintyä, jos tyyppimääritelmät ovat virheellisiä tai puuttuvat. Varmista, että sinulla on oikeat tyyppimääritelmät asennettuna kaikille käyttämillesi kirjastoille. Jos käytät JavaScript-kirjastoa, jolla ei ole tyyppimääritelmiä, harkitse mukautettujen tyyppimääritelmien luomista.

Käännösvirheet

Käännösvirheitä voi esiintyä, jos TypeScript-koodissasi on syntaksivirheitä tai tyyppivirheitä. Tarkista virheilmoitukset huolellisesti ja korjaa kaikki syntaksi- tai tyyppivirheet. Varmista, että koodisi noudattaa TypeScriptin koodauskäytäntöjä.

Yhteenveto

Hyvin määritetty tsconfig.json-tiedosto on olennainen onnistuneelle TypeScript-projektille. Ymmärtämällä olennaiset kääntäjäasetukset ja edistyneet konfiguraatiot voit optimoida kehitystyönkulkuasi, parantaa koodin laatua ja varmistaa yhteensopivuuden kohdeympäristön kanssa. Ajan sijoittaminen tsconfig.json:n oikeaan konfigurointiin maksaa itsensä takaisin pitkällä aikavälillä vähentämällä virheitä, parantamalla ylläpidettävyyttä ja tehostamalla käännösprosessia. Tämä johtaa tehokkaampaan ja luotettavampaan ohjelmistokehitykseen. Tässä annetut tiedot on suunniteltu yleispäteviksi, ja niiden pitäisi tarjota vankka perusta uuden projektin aloittamiseen TypeScriptillä.

Muista tutustua viralliseen TypeScript-dokumentaatioon saadaksesi ajantasaisimmat tiedot ja yksityiskohtaiset selitykset kaikista saatavilla olevista kääntäjäasetuksista. TypeScript-dokumentaatio on arvokas resurssi TypeScript-konfiguraation hienouksien ymmärtämiseen.